postcss-nested

What is postcss-nested?

The postcss-nested npm package allows developers to use nested syntax in CSS, similar to what is possible in preprocessors like SASS and LESS. It processes CSS files and unwraps nested rules following the CSS Nesting specification. This makes the CSS more readable and maintainable by organizing styles in a hierarchical manner.

What are postcss-nested's main functionalities?

Nesting Rules

This feature allows you to nest hover and other pseudo-class selectors inside the main selector block, making the CSS structure more intuitive and easier to manage.

a {
  color: red;
  &:hover {
    color: green;
  }
}

Nesting Properties

Enables grouping of properties under a common namespace, which can be particularly useful for font, margin, and padding definitions, leading to a cleaner and more organized style definition.

a {
  font: {
    weight: bold;
    size: 14px;
    family: Arial, sans-serif;
  }
}

Nesting At-Rules

Supports nesting of at-rules like @media, allowing for more streamlined and readable media query definitions within the relevant selector context.

@media (min-width: 768px) {
  body {
    background: lightblue;
    a {
      color: navy;
    }
  }
}

Other packages similar to postcss-nested

sass

Sass is a mature, stable, and powerful professional grade CSS extension language. It provides similar nesting functionalities but with a broader feature set for styling. Compared to postcss-nested, Sass offers more features like variables, mixins, and functions for more dynamic styling.

less

Less is a backward-compatible language extension for CSS. It also supports nesting, along with variables, mixins, and functions, similar to Sass. Less and postcss-nested offer comparable nesting capabilities, but Less includes additional features that extend CSS more comprehensively.

stylus

Stylus is an expressive, dynamic, and robust CSS preprocessor that supports nested selectors, variables, mixins, and arithmetic operations. It provides a more flexible syntax compared to postcss-nested, allowing for both a concise and expressive way to write CSS.

README

PostCSS Nested

PostCSS plugin to unwrap nested rules like how Sass does it.

.phone {
    &_title {
        width: 500px;
        @media (max-width: 500px) {
            width: auto;
        }
        body.is_dark & {
            color: white;
        }
    }
    img {
        display: block;
    }
}

.title {
  font-size: var(--font);

  @at-root html {
      --font: 16px
  }
}

will be processed to:

.phone_title {
    width: 500px;
}
@media (max-width: 500px) {
    .phone_title {
        width: auto;
    }
}
body.is_dark .phone_title {
    color: white;
}
.phone img {
    display: block;
}

.title {
  font-size: var(--font);
}
html {
  --font: 16px
}

Related plugins:

• Use postcss-atroot for @at-root at-rule to move nested child to the CSS root.
• Use postcss-current-selector after this plugin if you want to use current selector in properties or variables values.
• Use postcss-nested-ancestors before this plugin if you want to reference any ancestor element directly in your selectors with ^&.

Alternatives:

• See also postcss-nesting, which implements CSSWG draft (requires the & and introduces @nest).
• postcss-nested-props for nested properties like font-size.

Usage

Step 1: Install plugin:

npm install --save-dev postcss postcss-nested

Step 2: Check your project for existing PostCSS config: postcss.config.js in the project root, "postcss" section in package.json or postcss in bundle config.

If you do not use PostCSS, add it according to official docs and set this plugin in settings.

Step 3: Add the plugin to plugins list:

module.exports = {
  plugins: [
+   require('postcss-nested'),
    require('autoprefixer')
  ]
}

Options

bubble

By default, plugin will bubble only @media and @supports at-rules. You can add your custom at-rules to this list by bubble option:

postcss([ require('postcss-nested')({ bubble: ['phone'] }) ])

/* input */
a {
  color: white;
  @phone {
    color: black;
  }
}
/* output */
a {
  color: white;
}
@phone {
  a {
    color: black;
  }
}

unwrap

By default, plugin will unwrap only @font-face, @keyframes and @document at-rules. You can add your custom at-rules to this list by unwrap option:

postcss([ require('postcss-nested')({ unwrap: ['phone'] }) ])

/* input */
a {
  color: white;
  @phone {
    color: black;
  }
}
/* output */
a {
  color: white;
}
@phone {
  color: black;
}

preserveEmpty

By default, plugin will strip out any empty selector generated by intermediate nesting levels. You can set preserveEmpty to true to preserve them.

.a {
    .b {
        color: black;
    }
}

Will be compiled to:

.a { }
.a .b {
    color: black;
}

This is especially useful if you want to export the empty classes with postcss-modules.

Changelog

5.0.6

• Fixed custom at-rules nesting (by @bsak-shell).